Red Hat Enterprise Linux 8: Application Compatibility Guide

Red Hat Enterprise Linux 8: Application Compatibility Guide May 2019

Note: this article discusses Application Compatibility for Red Hat Enterprise Linux 8. For Red hat Enterprise Linux 7 please see the Red Hat Enterprise Linux 7: Application Compatibility GUIDE.

This guide is intended to provide software developers with Red Hat's guidelines regarding support of third-party applications across multiple releases of the Red Hat® Enterprise Linux® platform. ISV and customer applications can reduce or avoid migration issues between major and minor Red Hat® Enterprise Linux® versions by following these guidelines during application development.

This document describes the recommended uses of the system application programming (API) and binary interfaces (ABI) that are intended to provide compatibility across Red Hat® Enterprise Linux® releases. It outlines the tiered framework under which applications are considered compatible or not compatible.

The purpose of this document is to provide guidance regarding the stability of applications and libraries written for RHEL and run under newer releases of RHEL. The document focuses primarily on issues of software backwards-compatibility. Although backwards compatibility is the goal, development of new capabilities or security concerns sometimes makes that impractical. Hence, the guidelines and published policy may sometimes be overridden by the objective of providing our customers with the most competitive, secure, and capable systems possible; situational testing is always recommended. If additional clarification of these compatibility guidelines is required, please contact your Red Hat representative.

The following are basic terms used in this document:

Application programming interface (API) An API is a public interface implemented by a software program that enables it to interact with other software, including operating system components. The API is enforced at compile time and determines source compatibility, that is, whether application source code will compile similarly across different versions of the operating environment. It covers details such as:

Application binary interface (ABI) An ABI is a set of runtime conventions that interact with a compiled binary representation of a program. The ABI is enforced at runtime and it describes the low-level interface between an application and the operating environment. It covers details such as:

Tools such as compilers, linkers, runtime libraries, and the operating system itself needs to work with the ABI. The output of CLI tools is not considered a stable ABI.

ABI conformance A compiler conforms to an ABI if it generates code that follows all of the specifications enumerated by that ABI. A library conforms to an ABI if it is implemented according to that ABI. An application conforms to an ABI if it is built using tools that conform to that ABI and does not contain source code that changes behavior specified by the ABI or that otherwise bypasses the ABI.

Binary compatibility Binary compatibility means application binaries that are compiled for a specific ABI, generally for a combination of RHEL and a particular hardware architecture, will load and run similarly across different versions of RHEL. Application binaries consist of executable files, Dynamic Shared Objects (DSO), source, bytecode for interpreted just-in-time compiled languages, and their required data files.

Core persistent system infrastructure The core persistent system infrastructure refers to interfaces and externally available data structures that represent system state or provide a means of communicating with the system (for instance, system calls and header files).

Compatibility in a virtualized environment Virtual environments emulate bare-metal environments such that unprivileged applications that run on bare-metal environments will run, unmodified, in corresponding virtual environments. Virtual environments present simplified abstracted views of physical resources, so some differences may exist.

Compatibility in a Containerized environment Container environments provide isolation from the host OS, and at a minimum allows the application to run in an isolated manner from the host OS libraries and binaries, but still share the same OS kernel as all other containers on the host.

Major and minor releases A Red Hat major release represents a significant step in the development of a product (wholesale changes are usually reserved for major releases). Minor releases appear more frequently within the scope of a major release and generally represent smaller, incremental developmental steps.

Component An installable language, application, database, or other functional set of packages that run on RHEL. Components may be packaged as modules, Software Collections, or traditional RPMs. Components may be made available in container images.

Application Streams Application Streams make multiple versions of components available for installation on RHEL systems. Each different version is called a stream. PHP 7.2 is a stream, as is PHP 7.3. Application Streams may be packaged as SCLs, Modules, or traditional RPMs. Many Application Streams have a specified lifecycle, i.e. 3 years, and therefore are compatibility level 3 as described below.

Software Collection (SCL) A well-integrated, well-tested set of packages released together as a distinct unit. Software Collections deliver newer stable versions of components for use with Red Hat Enterprise Linux.

Modularity A module is a collection of RPMs with associated metadata, and are installed as a group or removed as a group. Modules are the mechanism by which some larger components, like databases, can deliver multiple versions. Modules are available in one or multiple streams. A module stream usually represents a major version of a piece of software, giving the user the option to choose what versions of the software packages they want to consume. Modules may be used for an Application Stream or may be dependent modules for other Modules. RPMs not listed in the module’s API are considered implementation details and are not subject to compatibility guarantees provided by the module.

SystemTap Static Probes SystemTap static probes are part of the SystemTap profiling and tracing framework. The probes are integrated into key system libraries to support profiling and debugging of applications and libraries.

File Hierarchy Standard (FHS) A file system structure which defines the names, locations, and permissions for various file types and directories. FHS-compliant file systems are compatible with each other and have the ability to mount a /usr/ partition as read only. The latter is important because the partition contains common executables and should not be changed by users.

CodeReady Linux Builder Repository The CodeReady Linux Builder repository contains components that a developer would use during the development of their RHEL application, but which would not be deployed in production. The components in the CodeReady Linux Builder repository are unsupported.

All components and packages in Red Hat Enterprise Linux are classified under one of the following four compatibility levels:

Compatibility level 1

Compatibility level 2

Compatibility level 3

Compatibility level 4

Compatibility levels for bare-metal configurations also apply to virtualized and containerized configurations except for any features that directly interact with hardware. Those features directly related to hardware have no API or ABI compatibility level. For example, applications that rely on Graphics Processing Unit (GPU) features cannot expect binary compatibility.

Red Hat requests that application developers validate that any behavior they depend on is explicitly defined in formal API documentation to prevent introducing dependencies on unspecified implementation-specific behavior or dependencies on bugs in a particular implementation of an API. For example, new releases of the GNU C library (glibc) may not be compatible with older releases if an application uses an undocumented API or relies on undefined behavior.

Your support representative will be happy to guide you through any specific questions you may have.

The following are exceptions to compatibility in RHEL.

SystemTap Static Probes

Static Linking with the C/C++ Runtime

C/C++ application sanitizers

CodeReady Linux Builder Repository

Red Hat recommends that application developers adopt the following principles in order to improve binary compatibility:

Use only libraries and applications listed in the compatibility level that suits your application needs.

Build applications using the published interfaces of a library. Non-published (internal) interfaces are subject to change at any time, which can cause instability in the dependent application if relied upon.

An application is only guaranteed to run correctly if it executes in an environment that is as new as the environment it was built in or newer. For example compiling your application on Red Hat Enterprise Linux 8.0 means your application is only guaranteed to run correctly on Red Hat Enterprise Linux 8.0 or later depending on the compatibility level of the components you depend upon.

Application developers should validate that any behavior they depend on is described in the published API documentation to prevent introducing dependencies on unspecified implementation-specific semantics or introducing dependencies on bugs in a particular implementation of an API.

For example, new releases of the GNU C library are not guaranteed to be compatible with older releases if the old behavior was not consistent with a published specification. Avoid static linking of libraries (C/C++). Static linking causes the executables to have their own version of the library. This increases the chance of an application not running predictably on a later version of the operating system as these library dependencies might have changed along the way. Linking applications dynamically is strongly recommended in order to avoid this problem.

Package applications using the RPM mechanism. RPM provides a software-packaging mechanism that includes a detailed specification of application dependencies. When creating RPMs, the following should be kept in mind: *Explicitly state all required runtime and build dependencies using the appropriate RPM syntax. It is recommended you rely on automatic dependency tracking where possible and avoid disabling via AutoReqProv, AutoReq, and AutoProv tags.

Follow the Filesystem Hierarchy Standard (FHS) version 2.3 or higher when installing programs. Third-party software should be installed to the '/opt' subdirectory. More information on the FHS is available at http://www.pathname.com/fhs/.

Note: During the life cycle of a major release, Red Hat makes commercially reasonable efforts to maintain the binary compatibility of the runtime environment across all minor releases and errata advisories. If necessary, Red Hat may make exceptions to this compatibility goal for critical impact security or other significant issues. Furthermore, as described above and in Appendix A, major releases of Red Hat Enterprise Linux contain a limited set of backward-compatible libraries included in previous major releases to allow for the easy migration of applications. Typically, Red Hat applies changes in such a way as to minimize the amount of change and to maintain binary compatibility.

For each compatibility level we define the binary packages which provide APIs and ABIs that are part of the compatibility level. As a convenience we list the source RPM from which those binary RPM(s) were built, but that source RPM is not considered to be a part of the compatibility level.

Note: This list below is a list of commonly used packages and is included for easy reference. It is not a complete list. Any component not included in a compatibility level listing in this document can be assumed to be level 2 and can be relied upon for compatibility within a major release, i.e. during the life of Red Hat Enterprise Linux 8.

The current set of level 3 content can be viewed here: Red Hat Enterprise Linux 8 Application Streams Life Cycle

Level 3 content has the same ABI and API compatibility as level 2 content, only the maintenance interval is different, as defined in the Application Stream table.